<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc Namespace Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Public API.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#namespaces">Namespaces</a> &#124;
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#var-members">Variables</a>  </div>
  <div class="headertitle"><div class="title">ipc Namespace Reference</div></div>
</div><!--header-->
<div class="contents">

<p>Catch-all namespace for the Flow-IPC project: A library/API in modern C++17 providing high-performance communication between processes.  
<a href="namespaceipc.html#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="namespaces" name="namespaces"></a>
Namespaces</h2></td></tr>
<tr class="memitem:namespaceipc_1_1bipc"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1bipc.html">bipc</a></td></tr>
<tr class="memdesc:namespaceipc_1_1bipc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for boost.interprocess namespace. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceipc_1_1fs"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1fs.html">fs</a></td></tr>
<tr class="memdesc:namespaceipc_1_1fs"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for <code>filesystem</code> namespace. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceipc_1_1session"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1session.html">session</a></td></tr>
<tr class="memdesc:namespaceipc_1_1session"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow-IPC module providing the broad lifecycle and shared-resource organization &ndash; via the <em>session</em> concept &ndash; in such a way as to make it possible for a given pair of processes A and B to set up <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> structured- or unstructured-message channels for general IPC, as well as to share data in SHared Memory (SHM). <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceipc_1_1shm"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1shm.html">shm</a></td></tr>
<tr class="memdesc:namespaceipc_1_1shm"><td class="mdescLeft">&#160;</td><td class="mdescRight">Modules for SHared Memory (SHM) support. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceipc_1_1transport"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1transport.html">transport</a></td></tr>
<tr class="memdesc:namespaceipc_1_1transport"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) between pairs of processes. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceipc_1_1util"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc_1_1util.html">util</a></td></tr>
<tr class="memdesc:namespaceipc_1_1util"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-IPC modules and/or do not fit into any other Flow-IPC module. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="typedef-members" name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:aa3192e586cc45d3e7c22463bf2760f89"><td class="memItemLeft" align="right" valign="top"><a id="aa3192e586cc45d3e7c22463bf2760f89" name="aa3192e586cc45d3e7c22463bf2760f89"></a>
using&#160;</td><td class="memItemRight" valign="bottom"><b>Error_code</b> = flow::Error_code</td></tr>
<tr class="memdesc:aa3192e586cc45d3e7c22463bf2760f89"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for <code>flow::Error_code</code> which is very common. <br /></td></tr>
<tr class="separator:aa3192e586cc45d3e7c22463bf2760f89"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa455c7f045059736578ca275fc1a851f"><td class="memTemplParams" colspan="2"><a id="aa455c7f045059736578ca275fc1a851f" name="aa455c7f045059736578ca275fc1a851f"></a>
template&lt;typename Signature &gt; </td></tr>
<tr class="memitem:aa455c7f045059736578ca275fc1a851f"><td class="memTemplItemLeft" align="right" valign="top">using&#160;</td><td class="memTemplItemRight" valign="bottom"><b>Function</b> = flow::Function&lt; Signature &gt;</td></tr>
<tr class="memdesc:aa455c7f045059736578ca275fc1a851f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for polymorphic functor holder which is very common. This is essentially <code>std::function</code>. <br /></td></tr>
<tr class="separator:aa455c7f045059736578ca275fc1a851f"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="enum-members" name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:a4ccdeed058222c635745a4dc830e99f7"><td class="memItemLeft" align="right" valign="top">enum class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">Log_component</a> { <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7a6fba12db09e5bebfaa04f6372c41c2cf">S_END_SENTINEL</a>
 }</td></tr>
<tr class="memdesc:a4ccdeed058222c635745a4dc830e99f7"><td class="mdescLeft">&#160;</td><td class="mdescRight">The <code>flow::log::Component</code> payload enumeration containing various log components used by Flow-IPC internal logging.  <a href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">More...</a><br /></td></tr>
<tr class="separator:a4ccdeed058222c635745a4dc830e99f7"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="var-members" name="var-members"></a>
Variables</h2></td></tr>
<tr class="memitem:a94386c9b549c1ea6be7e65e55c802d54"><td class="memItemLeft" align="right" valign="top">const boost::unordered_multimap&lt; <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">Log_component</a>, std::string &gt;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceipc.html#a94386c9b549c1ea6be7e65e55c802d54">S_IPC_LOG_COMPONENT_NAME_MAP</a></td></tr>
<tr class="memdesc:a94386c9b549c1ea6be7e65e55c802d54"><td class="mdescLeft">&#160;</td><td class="mdescRight">The map generated by <code>flow::log</code> macro magic that maps each enumerated value in <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7" title="The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...">ipc::Log_component</a> to its string representation as used in log output and verbosity config.  <a href="namespaceipc.html#a94386c9b549c1ea6be7e65e55c802d54">More...</a><br /></td></tr>
<tr class="separator:a94386c9b549c1ea6be7e65e55c802d54"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >Catch-all namespace for the Flow-IPC project: A library/API in modern C++17 providing high-performance communication between processes. </p>
<p >It includes schema-based structured message definition and zero-copy transport between processes. It also includes a SHared Memory (SHM) module for direct allocation and related needs; and particular support for passing references to such <em>bulk</em> objects through the aforementioned messaging transport system.</p>
<dl class="section note"><dt>Note</dt><dd>Nomenclature: The project is called Flow-IPC.</dd></dl>
<p>From the user's perspective, one should view this namespace as the "root," meaning it consists of two parts:</p><ul>
<li>Symbols directly in Flow-IPC: The absolute most basic, commonly used symbols (such as the alias <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">ipc::Error_code</a>). There should be only a handful of these, and they are likely to be small.<ul>
<li>In particular this includes <code>enum class</code> <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7" title="The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...">ipc::Log_component</a> which defines the set of possible <code>flow::log::Component</code> values logged from within all modules of Flow-IPC. See end of <a class="el" href="common_8hpp.html">common.hpp</a>.</li>
</ul>
</li>
<li>Sub-namespaces (like <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>, <a class="el" href="namespaceipc_1_1util.html" title="Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-I...">ipc::util</a>), each of which represents an Flow-IPC <em>module</em> providing certain grouped functionality. The modules are discussed just below.</li>
</ul>
<h2>Flow-IPC modules overview </h2>
<p >Unlike with, say, Boost or Flow, the user of Flow-IPC should be familiar with the totality of its modules. They're interrelated and to be used together in a typical application. Contrast with how one might use <code>flow::log</code> but not <code>flow::async</code>, or boost.asio but not boost.random. Summary of modules follows:</p>
<ul>
<li><em><a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a></em>: It allows for low-level (unstructured) and structured message passing between each given pair of processes A and B. This is really <em>the point</em> of Flow-IPC, meaning wanting to use <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> is the reason one links/includes Flow-IPC in their application in the first place.<ul>
<li><em><a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a></em> contains the structured-message facilities. To define a structured message, the user is expected to write a <em>schema</em> for it. As of this writing schemas are to be written in the Cap'n Proto (capnp) domain-specific language (DSL). Hence <a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a> has capnp as a dependency.<ul>
<li><em><a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a></em> contains some important items, albeit not ones <em>typically</em> directly mentioned by user code, that power the ability to place structured messages directly in SHM, thus enabling end-to-end <em>zero-copy</em> of all messages passed through <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a>.</li>
</ul>
</li>
</ul>
</li>
<li><em><a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a></em>: Before a given process pair A and B talks via <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>, they (typically) will want to establish a broad conceptual connection (called a <em>session</em>) within the context of which all the talking occurs. <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> is concerned with establishing such sessions, so that most user code can then mostly forget about that and use <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> to communicate. It includes safety measures like authentication/tokens, but these should be mostly invisible in day-to-day coding of IPC logic via <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>. It <em>is</em> possible to establish <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> pipes without sessions, and for smaller and/or legacy applications and/or prototyping that may be a reasonable approach.<ul>
<li><em><a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a></em> conventionally contains SHM-enabled session functionality. The location of a given set of classes will mirror the <a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a> facilities to which those SHM-enabled sessions provides access. For example <a class="el" href="namespaceipc_1_1session_1_1shm_1_1classic.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-classic (ipc::shm::clas...">ipc::session::shm::classic</a> contains SHM-classic sessions which provide access to arenas supplied by <a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a>. Similarly <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend_1_1jemalloc.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-jemalloc (ipc::shm::are...">ipc::session::shm::arena_lend::jemalloc</a> contains SHM-jemalloc sessions &lt;=&gt; core arena facilities in ipc::shm::arena_lend::jemalloc. Note the 1-1 naming of namespaces in both cases.</li>
</ul>
</li>
<li><em><a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a></em>: It provides explicit shared memory (SHM) functionality, including allocating in SHM &ndash; vaguely analogously to using the regular heap. <a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a> and <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> are co-designed to support transmitting references to SHM-stored objects. <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> treats setup of SHM arenas for (direct or background) use in a given session as an important, albeit optional, capability. Unless the user wants to explicitly place data structures (such as <code>struct</code>s and STL containers) into SHM &ndash; which is an advanced but sometimes desirable capability &ndash; direct use of <a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a> is not necessary.</li>
<li><em><a class="el" href="namespaceipc_1_1util.html" title="Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-I...">ipc::util</a></em>: Miscellaneous items. That said some of these are quite important and oft-used throughout other modules. Here we single out, in particular, <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">ipc::util::Shared_name</a> and <a class="el" href="structipc_1_1util_1_1Native__handle.html" title="A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.">ipc::util::Native_handle</a>.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>Nomenclature: We refer to Cap'n Proto as capnp, lower-case, no backticks. Keep to this consistent convention in comments.</dd></dl>
<p>The above text views Flow-IPC somewhat as a monolithic whole. Indeed the present documentation generally treats the entirety of Flow-IPC as available and usable, even though the are various sub-namespaces as shown that break the monolith into cooperating modules. When it comes to practical needs, this view is sufficient. Really, most users will (1) start a session (using <a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a> for max performance), (2) use the session to create 1+ <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">ipc::transport::Channel</a>, (3) typically upgrade each to <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">ipc::transport::struc::Channel</a> immediately (a one-liner), (3) use the <code>struc::Channel</code> API to send/receive messages with automatic end-to-end zero-copy performance. (4) Optionally one can also access a SHM-arena for direct C++ object placement and access in SHM; the SHM arenas are available from the session object.</p>
<p >That said, read on if you want to maintain or otherwise deeper understand Flow-IPC. There's a deeper organization of this monolith, in which one builds up the whole out of smaller parts, where we generally avoid circular dependencies (A needs B, and B needs A). Let's briefly go through the process of naming the most basic parts and then showing what depends on them, and so on, until everything is listed in bottom-up order. To wit:</p>
<ol type="1">
<li><a class="el" href="namespaceipc_1_1util.html" title="Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-I...">ipc::util</a>: This contains basic, simple building blocks. <a class="el" href="classipc_1_1util_1_1Shared__name.html" title="String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...">ipc::util::Shared_name</a> is used to name various shared resource throughout Flow-IPC. <a class="el" href="structipc_1_1util_1_1Native__handle.html" title="A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.">ipc::util::Native_handle</a> is a trivial wrapper around a native handle (FD in POSIX/Linux/Unix parlance). There are various other items which you'll note when they're mentioned.<ul>
<li>Dependents: Essentially all other code routinely depends on <a class="el" href="namespaceipc_1_1util.html" title="Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-I...">ipc::util</a>.</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>, <em>excluding</em> <a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a>: This is the transport <em>core layer</em>. Think of this as wrappers around legacy IPC transport APIs with which you may already be familiar: e.g., Unix domain sockets. There are key concepts, including <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">ipc::transport::Blob_sender</a> and <code>Blob_receiver</code> (+ <code>Native_handle_{send|receiv}er</code>); and their implementations over the aforementioned specific low-level transports (Unix domain sockets, MQs as of this writing).<ul>
<li>Dependents:<ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a>. The key point is <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a></code>, the absolute most important object (possibly in all of Flow-IPC), adapts <code><a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a></code>, including for example leveraging that an unstructured <code>Channel</code> might contain a blobs pipe <em>and</em> a native handles pipe.</li>
<li><a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> depends on <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>, in that the most important function of an <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">ipc::session::Session</a> is to <em>painlessly create</em> (open) <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">ipc::transport::Channel</a> objects. You start a session to the opposing process; and you use that session to create 1+ channels; then you speak over these channels as needed. (<em>If</em> you want to speak using structured messages, you upgrade a <code><a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a></code> to a <code><a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">transport::struc::Channel</a></code>: a structured channel.)</li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a>: The transport <em>structured layer</em> builds on top of (1) the core layer and (2) capnp. <code>struc::Channel</code> adapts an unstructured <code>Channel</code>, allowing efficient transmission of structured messages filled-out according to user-provided capnp-generated schema(s). At its simplest, wihout the (spoiler alert) <code>shm</code> sub-namespace, an out-message is backed by the regular heap (<code>new</code>, etc.); and a received in-message is a copy also backed by the regular heap of the recipient process.<ul>
<li>Dependents: <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> and <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend.html" title="Bundles ipc::session::shm support for the various arena-lend-style SHM-providers, as of this writing ...">ipc::session::shm::arena_lend</a>, for orthogonal reasons, use <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">ipc::transport::struc::Channel</a> for their internal purposes. It's a useful guy!</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>, <em>excluding</em> <a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a>: This is the core support for sessions, which are how one painlessly begins a conversation between your process and the opposing process. Without it you'll need to worry about low-level resource naming and cleanup; with it, it's taken care-of &ndash; just open channels and use them. Spoiler alert: the sub-namespace <code>shm</code> (see below) will add SHM capabilities.<ul>
<li>Dependents: <a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a> builds on top of this and hence depends on it.</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">ipc::shm::stl</a>: A couple of key facilities here enable storage of STL-compliant C++ data structures directly in SHM; e.g., a map from strings to vectors of strings and <code>struct</code>s and... etc. You, the user, will <em>only</em> directly use this, if you need such functionality. If you only need to send structured messages with max perf (which internally is achieved using SHM), then you need not directly mention this.<ul>
<li>Dependents:<ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a> "eats our own dog food" by internally representing certain data structures using STL-compliant APIs, including <code>list&lt;&gt;</code> and <code>flow::util::Blob</code>.</li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a>: This essentially just adds <code>shm::Builder</code> and <code>shm::Reader</code> which are impls of <a class="el" href="classipc_1_1transport_1_1struc_1_1Struct__builder.html" title="A documentation-only concept defining the behavior of an object capable of zero-copy-serializing,...">ipc::transport::struc::Struct_builder</a> and <code>Struct_reader</code> concepts that enable end-to-end zero-copy transmission of any capnp-schema-based message &ndash; as long as one has certain key SHM-enabling objects, most notably a <code>Shm_arena</code>.<ul>
<li>Dependents:<ul>
<li><a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a> mentions <code>shm::Builder</code> and <code>shm::Reader</code> in a key convenience alias.</li>
<li>The bottom line is, if you use SHM-enabled sessions &ndash; which is at least easily the most convenient way to obtain end-to-end zero-copy perf when transmitting structured messages along channels &ndash; then <a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a> shall be used, most likely without your needing to mention it or worry about it.</li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a>: This is a <em>SHM-provider</em> (of SHM-arenas); namely the <em>SHM-classic</em> provider. The core item is <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">ipc::shm::classic::Pool_arena</a>, a "classic" single-segment (pool) SHM arena with a simple arena-allocation algorithm.<ul>
<li>Dependents: <a class="el" href="namespaceipc_1_1session_1_1shm_1_1classic.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-classic (ipc::shm::clas...">ipc::session::shm::classic</a> provides SHM-enabled sessions with this SHM-provider as the required SHM engine. Naturally in so doing it depends on <a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a>, especially <code>classic::Pool_arena</code>.</li>
</ul>
</li>
<li>ipc::shm::arena_lend (more specifically ipc::shm::arena_lend::jemalloc): This is the other <em>SHM-provider</em> (of SHM-arenas); namely the <em>SHM-jemalloc</em> provider. The core item is <code>jemalloc::Ipc_arena</code>. is <code>Pool_arena</code>, a "classic" single-segment (pool) SHM arena with a simple arena-allocation algorithm.<ul>
<li>Dependents: <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend_1_1jemalloc.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-jemalloc (ipc::shm::are...">ipc::session::shm::arena_lend::jemalloc</a> provides SHM-enabled sessions with this SHM-provider as the required SHM engine. Naturally in so doing it depends on ipc::shm::arena_lend::jemalloc, especially <code>jemalloc::Ipc_arena</code>.</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a>: This namespace adds SHM-enabled sessions. Namely that adds two capabilities; one, to easily get end-to-end zero-copy performance along <code>struc::Channel</code> objects opened via these sessions. And, optionally, two: To have direct access to SHM-arena(s) in which to place and access C++ objects.<ul>
<li>More specifically: <a class="el" href="namespaceipc_1_1session_1_1shm_1_1classic.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-classic (ipc::shm::clas...">ipc::session::shm::classic</a> = SHM-classic-provider-enabled sessions; <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend_1_1jemalloc.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-jemalloc (ipc::shm::are...">ipc::session::shm::arena_lend::jemalloc</a> = SHM-jemalloc-provider-enabled sessions.<ul>
<li>Dependents: none (inside Flow-IPC).</li>
</ul>
</li>
</ul>
</li>
</ol>
<p >Again &ndash; there's no need to understand all this, if you're just using Flow-IPC in the expected mainstream ways. Nevertheless it could be a useful, if wordy, map to the building blocks of Flow-IPC and how they interact.</p>
<h2>Distributed sub-components (libraries) </h2>
<p >The above describes Flow-IPC as a whole. Generally we recommend a distribution of Flow-IPC which includes all the pieces, to be used at will. That said, for reasons outside our scope here, this project is actually distributed in a few parts, each of which is a library with a set of header files. (The generated documentation is created from all of them together, and therefore various comments aren't particularly shy about referring to items across the boundaries between those parts.) These parts (libraries) are:</p>
<ul>
<li><code>ipc_core</code>: Contains: <a class="el" href="namespaceipc_1_1util.html" title="Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-I...">ipc::util</a>, <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> (excluding <a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a>).</li>
<li><code>ipc_transport_structured</code>: Contains: <a class="el" href="namespaceipc_1_1transport_1_1struc.html" title="Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifical...">ipc::transport::struc</a> (excluding <a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a>).</li>
<li><code>ipc_session</code>: Contains: <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> (excluding <a class="el" href="namespaceipc_1_1session_1_1shm.html" title="ipc::session sub-namespace that groups together facilities for SHM-backed sessions,...">ipc::session::shm</a>).</li>
<li><code>ipc_shm</code>: Contains: <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">ipc::shm::stl</a>, <a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm.html" title="Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::str...">ipc::transport::struc::shm</a> (including <a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm_1_1classic.html" title="As of this writing certain convenience aliases supplied for the SHM-classic SHM-provider as pertains ...">ipc::transport::struc::shm::classic</a> but excluding all other such sub-namespaces), <a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a> + <a class="el" href="namespaceipc_1_1session_1_1shm_1_1classic.html" title="Support for SHM-backed ipc::session sessions and session-servers with the SHM-classic (ipc::shm::clas...">ipc::session::shm::classic</a>.</li>
<li><code>ipc_shm_arena_lend</code>: Contains: <a class="el" href="namespaceipc_1_1transport_1_1struc_1_1shm_1_1arena__lend.html" title="See parent ipc::transport::struc::shm and at least sub-namespace ipc::transport::struc::shm::arena_le...">ipc::transport::struc::shm::arena_lend</a>, ipc::shm::arena_lend + <a class="el" href="namespaceipc_1_1session_1_1shm_1_1arena__lend.html" title="Bundles ipc::session::shm support for the various arena-lend-style SHM-providers, as of this writing ...">ipc::session::shm::arena_lend</a>.</li>
</ul>
<p >The dependencies between these are as follows:</p><ul>
<li><code>ipc_core</code> &lt;- each of the others;</li>
<li><code>ipc_transport_structured</code> &lt;- <code>ipc_session</code> &lt;- <code>ipc_shm</code> &lt;- <code>ipc_shm_arena_lend</code>.<ul>
<li>(There are are, e.g., direct dependencies redundant to the above, such as how <code>ipc_shm_arena_lend</code> depends on <code>ipc_transport_structured</code> in certain key internal impl details. We are not pointing out every direct dependency here, leaving it out as long as it's implied by another indirect dependency such as <code>ipc_shm_arena_lend</code> indirectly depending on <code>ipc_transport_structured</code> via several others. )</li>
</ul>
</li>
</ul>
<p >Each one, in the source code, is in a separate top-level directory; and generates a separate static library. However, their directory structures &ndash; and accordingly the namespace trees &ndash; overlap in naming, which manifests itself when 2 or more of the sub-components are installed together. For example <code>ipc_session</code> places <code>ipc/session</code> into the <code>#include</code> tree; and <code>ipc_shm</code> places <code>ipc/session/shm/classic</code> within that.</p>
<h2>Relationship with Flow and Boost </h2>
<p >Flow-IPC requires Flow and Boost, not only for internal implementation purposes but also in some of its APIs. For example, <code>flow::log</code> is the assumed logging system, and <code>flow::Error_code</code> and related conventions are used for error reporting; and <code>boost::interprocess</code> and <code>boost::thread</code> APIs may be exposed at times.</p>
<p >Moreover, Flow-IPC shares Flow "DNA" in terms of coding style, error, logging, documentation, etc., conventions. Flow-IPC and Flow itself are also more loosely inspired by Boost "DNA." (For example: <code>snake_case</code> for identifier naming is inherited from Flow, which inherits it more loosely from Boost; the error reporting API convention is taken from Flow which uses a modified version of the boost.asio convention.)</p>
<h2>Documentation / Doxygen </h2>
<p >All code in the project proper follows a high standard of documentation, almost solely via comments therein (plus a guided Manual in manual/....dox.txt files, also as Doxygen-read comments). The standards and mechanics w/r/t documentation are entirely inherited from Flow. Therefore, see the <code>namespace flow</code> doc header's "Documentation / Doxygen" section. It applies verbatim here (within reason). (Spoiler alert: Doc header comments on most entities (classes, functions, ...) are friendly to doc web page generation by Doxygen. Doxygen is a tool similar to Javadoc.)</p>
<p >The only exception to this is the addition of the aforementioned guided Manual as well which Flow lacks as of this writing (for the time being).</p>
<h2>Using Flow-IPC modules </h2>
<p >This section discusses usability topics that apply to all Flow-IPC modules including hopefully any future ones but definitely all existing ones as of this writing.</p>
<h3>Error reporting</h3>
<p >The standards and mechanics w/r/t error reporting are entirely inherited from Flow. Therefore, see the <code>namespace flow</code> doc header's "Error reporting" section. It applies verbatim (within reason) here.</p>
<h3>Logging</h3>
<p >We use the Flow log module, in <code>flow::log</code> namespace, for logging. We are just a consumer, but this does mean the Flow-IPC user must supply a <code>flow::log::Logger</code> into various APIs in order to enable logging. (Worst-case, passing <code>Logger == null</code> will make it log nowhere.) See <code>flow::log</code> docs. Spoiler alert: You can hook it up to whatever logging output/other logging API you desire, or it can log for you in certain common ways including console and rotated files. </p>
</div><h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="a4ccdeed058222c635745a4dc830e99f7" name="a4ccdeed058222c635745a4dc830e99f7"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4ccdeed058222c635745a4dc830e99f7">&#9670;&nbsp;</a></span>Log_component</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">enum class <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">ipc::Log_component</a></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">strong</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>The <code>flow::log::Component</code> payload enumeration containing various log components used by Flow-IPC internal logging. </p>
<p >Internal Flow-IPC code specifies members thereof when indicating the log component for each particular piece of logging code. Flow-IPC user specifies it, albeit very rarely, when configuring their program's logging such as via <code>flow::log::Config::init_component_to_union_idx_mapping()</code> and <code>flow::log::Config::init_component_names()</code>.</p>
<p >If you are reading this in Doxygen-generated output (likely a web page), be aware that the individual <code>enum</code> values are not documented right here, because <code>flow::log</code> auto-generates those via certain macro magic, and Doxygen cannot understand what is happening. However, you will find the same information directly in the source file <code>log_component_enum_declare.macros.hpp</code> (if the latter is clickable, click to see the source).</p>
<h3>Details regarding overall log system init in user program</h3>
<p >See comment in similar place in <code>flow/common.hpp</code>. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="a4ccdeed058222c635745a4dc830e99f7a6fba12db09e5bebfaa04f6372c41c2cf" name="a4ccdeed058222c635745a4dc830e99f7a6fba12db09e5bebfaa04f6372c41c2cf"></a>S_END_SENTINEL&#160;</td><td class="fielddoc"><p >CAUTION &ndash; see <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7" title="The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...">ipc::Log_component</a> doc header for directions to find actual members of this <code>enum class</code>. </p>
<p >This entry is a placeholder for Doxygen purposes only, because of the macro magic involved in generating the actual <code>enum class</code>. </p>
</td></tr>
</table>

</div>
</div>
<h2 class="groupheader">Variable Documentation</h2>
<a id="a94386c9b549c1ea6be7e65e55c802d54" name="a94386c9b549c1ea6be7e65e55c802d54"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a94386c9b549c1ea6be7e65e55c802d54">&#9670;&nbsp;</a></span>S_IPC_LOG_COMPONENT_NAME_MAP</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const boost::unordered_multimap&lt;<a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7">Log_component</a>, std::string&gt; ipc::S_IPC_LOG_COMPONENT_NAME_MAP</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">extern</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>The map generated by <code>flow::log</code> macro magic that maps each enumerated value in <a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7" title="The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...">ipc::Log_component</a> to its string representation as used in log output and verbosity config. </p>
<p >Flow-IPC user specifies, albeit very rarely, when configuring their program's logging via <code>flow::log::Config::init_component_names()</code>.</p>
<p >As an Flow-IPC user, you can informally assume that if the component <code>enum</code> member is called <code>S_SOME_NAME</code>, then its string counterpart in this map will be auto-computed to be <code>"SOME_NAME"</code> (optionally prepended with a prefix as supplied to <code>flow::log::Config::init_component_names()</code>). This is achieved via <code>flow::log</code> macro magic.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="namespaceipc.html#a4ccdeed058222c635745a4dc830e99f7" title="The flow::log::Component payload enumeration containing various log components used by Flow-IPC inter...">ipc::Log_component</a> first. </dd></dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:23 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
